Skip to content

feat(examples): add wa-sqlite OPFS persistence demo#1329

Open
kevin-dp wants to merge 4 commits intomainfrom
examples/offline-transactions-wa-sqlite-demo
Open

feat(examples): add wa-sqlite OPFS persistence demo#1329
kevin-dp wants to merge 4 commits intomainfrom
examples/offline-transactions-wa-sqlite-demo

Conversation

@kevin-dp
Copy link
Contributor

@kevin-dp kevin-dp commented Mar 4, 2026

Summary

  • add the persisted sync metadata RFC and phased implementation plan covering core metadata transactions, SQLite persistence, query collection ownership/retention, and Electric resume state
  • implement transactional row and collection metadata plumbing across @tanstack/db, db-sqlite-persisted-collection-core, query-db-collection, and electric-db-collection
  • keep the branch's existing wa-sqlite OPFS example/demo changes and associated example setup updates

Test plan

  • Run pnpm vitest --run packages/db/tests/collection.test.ts
  • Run pnpm --filter @tanstack/query-db-collection exec vitest run tests/query.test.ts --coverage.enabled false
  • Run pnpm --filter @tanstack/electric-db-collection exec vitest run tests/electric.test.ts --coverage.enabled false
  • Run pnpm --filter @tanstack/db-sqlite-persisted-collection-core exec vitest run tests/persisted.test.ts tests/sqlite-core-adapter.test.ts --coverage.enabled false

Notes

  • The SQLite persisted-collection package tests are functionally green, but the package-local Vitest run still reports a pre-existing type-resolution issue for @standard-schema/spec in src/persisted.ts after the tests complete.
  • This branch already contained the wa-sqlite example/demo work before the persisted sync metadata commits were added, so that diff is still part of this PR.

@changeset-bot
Copy link

changeset-bot bot commented Mar 4, 2026

⚠️ No Changeset found

Latest commit: 6a9d96d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@pkg-pr-new
Copy link

pkg-pr-new bot commented Mar 4, 2026

More templates

@tanstack/angular-db

npm i https://pkg.pr.new/TanStack/db/@tanstack/angular-db@1329

@tanstack/db

npm i https://pkg.pr.new/TanStack/db/@tanstack/db@1329

@tanstack/db-browser-wa-sqlite-persisted-collection

npm i https://pkg.pr.new/TanStack/db/@tanstack/db-browser-wa-sqlite-persisted-collection@1329

@tanstack/db-ivm

npm i https://pkg.pr.new/TanStack/db/@tanstack/db-ivm@1329

@tanstack/db-react-native-sqlite-persisted-collection

npm i https://pkg.pr.new/TanStack/db/@tanstack/db-react-native-sqlite-persisted-collection@1329

@tanstack/db-sqlite-persisted-collection-core

npm i https://pkg.pr.new/TanStack/db/@tanstack/db-sqlite-persisted-collection-core@1329

@tanstack/electric-db-collection

npm i https://pkg.pr.new/TanStack/db/@tanstack/electric-db-collection@1329

@tanstack/offline-transactions

npm i https://pkg.pr.new/TanStack/db/@tanstack/offline-transactions@1329

@tanstack/powersync-db-collection

npm i https://pkg.pr.new/TanStack/db/@tanstack/powersync-db-collection@1329

@tanstack/query-db-collection

npm i https://pkg.pr.new/TanStack/db/@tanstack/query-db-collection@1329

@tanstack/react-db

npm i https://pkg.pr.new/TanStack/db/@tanstack/react-db@1329

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/TanStack/db/@tanstack/rxdb-db-collection@1329

@tanstack/solid-db

npm i https://pkg.pr.new/TanStack/db/@tanstack/solid-db@1329

@tanstack/svelte-db

npm i https://pkg.pr.new/TanStack/db/@tanstack/svelte-db@1329

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/TanStack/db/@tanstack/trailbase-db-collection@1329

@tanstack/vue-db

npm i https://pkg.pr.new/TanStack/db/@tanstack/vue-db@1329

commit: 6a9d96d

@github-actions
Copy link
Contributor

github-actions bot commented Mar 4, 2026

Size Change: 0 B

Total Size: 110 kB

ℹ️ View Unchanged
Filename Size
./packages/db/dist/esm/collection/change-events.js 1.39 kB
./packages/db/dist/esm/collection/changes.js 1.38 kB
./packages/db/dist/esm/collection/cleanup-queue.js 810 B
./packages/db/dist/esm/collection/events.js 434 B
./packages/db/dist/esm/collection/index.js 3.69 kB
./packages/db/dist/esm/collection/indexes.js 2.35 kB
./packages/db/dist/esm/collection/lifecycle.js 1.76 kB
./packages/db/dist/esm/collection/mutations.js 2.47 kB
./packages/db/dist/esm/collection/state.js 5.2 kB
./packages/db/dist/esm/collection/subscription.js 3.71 kB
./packages/db/dist/esm/collection/sync.js 2.43 kB
./packages/db/dist/esm/collection/transaction-metadata.js 144 B
./packages/db/dist/esm/deferred.js 207 B
./packages/db/dist/esm/errors.js 4.83 kB
./packages/db/dist/esm/event-emitter.js 748 B
./packages/db/dist/esm/index.js 2.85 kB
./packages/db/dist/esm/indexes/auto-index.js 777 B
./packages/db/dist/esm/indexes/base-index.js 766 B
./packages/db/dist/esm/indexes/btree-index.js 2.17 kB
./packages/db/dist/esm/indexes/lazy-index.js 1.24 kB
./packages/db/dist/esm/indexes/reverse-index.js 538 B
./packages/db/dist/esm/local-only.js 890 B
./packages/db/dist/esm/local-storage.js 2.1 kB
./packages/db/dist/esm/optimistic-action.js 359 B
./packages/db/dist/esm/paced-mutations.js 496 B
./packages/db/dist/esm/proxy.js 3.75 kB
./packages/db/dist/esm/query/builder/functions.js 792 B
./packages/db/dist/esm/query/builder/index.js 5.15 kB
./packages/db/dist/esm/query/builder/ref-proxy.js 1.05 kB
./packages/db/dist/esm/query/compiler/evaluators.js 1.62 kB
./packages/db/dist/esm/query/compiler/expressions.js 430 B
./packages/db/dist/esm/query/compiler/group-by.js 2.69 kB
./packages/db/dist/esm/query/compiler/index.js 3.62 kB
./packages/db/dist/esm/query/compiler/joins.js 2.11 kB
./packages/db/dist/esm/query/compiler/order-by.js 1.5 kB
./packages/db/dist/esm/query/compiler/select.js 1.11 kB
./packages/db/dist/esm/query/effect.js 4.78 kB
./packages/db/dist/esm/query/expression-helpers.js 1.43 kB
./packages/db/dist/esm/query/ir.js 784 B
./packages/db/dist/esm/query/live-query-collection.js 360 B
./packages/db/dist/esm/query/live/collection-config-builder.js 7.63 kB
./packages/db/dist/esm/query/live/collection-registry.js 264 B
./packages/db/dist/esm/query/live/collection-subscriber.js 1.94 kB
./packages/db/dist/esm/query/live/internal.js 145 B
./packages/db/dist/esm/query/live/utils.js 1.57 kB
./packages/db/dist/esm/query/optimizer.js 2.62 kB
./packages/db/dist/esm/query/predicate-utils.js 2.97 kB
./packages/db/dist/esm/query/query-once.js 359 B
./packages/db/dist/esm/query/subset-dedupe.js 960 B
./packages/db/dist/esm/scheduler.js 1.3 kB
./packages/db/dist/esm/SortedMap.js 1.3 kB
./packages/db/dist/esm/strategies/debounceStrategy.js 247 B
./packages/db/dist/esm/strategies/queueStrategy.js 428 B
./packages/db/dist/esm/strategies/throttleStrategy.js 246 B
./packages/db/dist/esm/transactions.js 2.9 kB
./packages/db/dist/esm/utils.js 927 B
./packages/db/dist/esm/utils/browser-polyfills.js 304 B
./packages/db/dist/esm/utils/btree.js 5.61 kB
./packages/db/dist/esm/utils/comparison.js 1.05 kB
./packages/db/dist/esm/utils/cursor.js 457 B
./packages/db/dist/esm/utils/index-optimization.js 1.54 kB
./packages/db/dist/esm/utils/type-guards.js 157 B
./packages/db/dist/esm/virtual-props.js 360 B

compressed-size-action::db-package-size

@github-actions
Copy link
Contributor

github-actions bot commented Mar 4, 2026

Size Change: 0 B

Total Size: 4.23 kB

ℹ️ View Unchanged
Filename Size
./packages/react-db/dist/esm/index.js 249 B
./packages/react-db/dist/esm/useLiveInfiniteQuery.js 1.32 kB
./packages/react-db/dist/esm/useLiveQuery.js 1.34 kB
./packages/react-db/dist/esm/useLiveQueryEffect.js 355 B
./packages/react-db/dist/esm/useLiveSuspenseQuery.js 559 B
./packages/react-db/dist/esm/usePacedMutations.js 401 B

compressed-size-action::react-db-package-size

@kevin-dp kevin-dp force-pushed the examples/offline-transactions-wa-sqlite-demo branch 3 times, most recently from 490d519 to d7a150d Compare March 5, 2026 12:26
@tobacode
Copy link

tobacode commented Mar 6, 2026

The fetchWithRetry keeps retrying with exponential backoff, causing an infinite "Loading todos"

The infinite retry loop here might be related to #1065

@kevin-dp kevin-dp changed the base branch from cursor/persistence-plan-design-doc-f6d0 to kevin/persistence March 12, 2026 09:22
@kevin-dp kevin-dp force-pushed the kevin/persistence branch 4 times, most recently from 37c3bf5 to ca46819 Compare March 16, 2026 11:30
Base automatically changed from kevin/persistence to main March 16, 2026 12:48
@kevin-dp kevin-dp force-pushed the examples/offline-transactions-wa-sqlite-demo branch from dc17281 to 2841627 Compare March 16, 2026 12:51
…ctions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@kevin-dp kevin-dp force-pushed the examples/offline-transactions-wa-sqlite-demo branch from 2455641 to e22631a Compare March 16, 2026 13:06
@samwillis
Copy link
Collaborator

GPT5.4 review:


Findings

  • High: examples/react/offline-transactions does not production-build on this branch. Running pnpm build in that example fails with Vite/Rollup resolving @tanstack/db-sqlite-persisted-collection-core. The new config aliases @tanstack/db-browser-wa-sqlite-persisted-collection straight to its source entry, but that entry immediately re-exports persistedCollectionOptions from the core workspace package, and this example never aliases or depends on that package. So the new wa-sqlite route currently only works in a partial local-dev setup and is not merge-ready as a shippable example.
resolve: {
  alias: {
    // Resolve to source so Vite can process the ?worker import natively
    '@tanstack/db-browser-wa-sqlite-persisted-collection': path.resolve(
      __dirname,
      `../../../packages/db-browser-wa-sqlite-persisted-collection/src/index.ts`,
    ),
  },
},
export { createBrowserWASQLitePersistence } from './browser-persistence'
export { openBrowserWASQLiteOPFSDatabase } from './opfs-database'
export { BrowserCollectionCoordinator } from './browser-coordinator'
export type { BrowserCollectionCoordinatorOptions } from './browser-coordinator'
export { persistedCollectionOptions } from '@tanstack/db-sqlite-persisted-collection-core'

Assumptions

The PR body for #1329 already has “Replace the workspace dependencies...” unchecked, so this may be known. I’m still calling it out because it is a real blocker today, not just cleanup.

Residual Risk

I didn’t count the existing SPA/API example breakage against this PR since the author already called that out and it predates these changes. I also didn’t do browser smoke testing after finding the build blocker.

kevin-dp and others added 3 commits March 16, 2026 16:11
The browser wa-sqlite package source re-exports from the core package,
so resolving from source requires both aliases for the build to succeed.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@AntonOfTheWoods
Copy link

@kevin-dp maybe for a different PR, but the current (including in main) state of offline-transactions still has lots of copy-pasted stuff in the docs and names (eg, "name": "tanstack-start-example-basic" in package.json) that makes getting things running harder than it could be. Were you going to take care of that or would you like a separate docs PR?

@kevin-dp
Copy link
Contributor Author

@kevin-dp maybe for a different PR, but the current (including in main) state of offline-transactions still has lots of copy-pasted stuff in the docs and names (eg, "name": "tanstack-start-example-basic" in package.json) that makes getting things running harder than it could be. Were you going to take care of that or would you like a separate docs PR?

Hi @AntonOfTheWoods, i'd prefer fixing that in a separate PR and keep this one focused.

@AntonOfTheWoods
Copy link

Ok. I tried running it and was a little surprised to see it doesn't even build. The code depends on methods that haven't existed for months in dependencies...

@samwillis samwillis marked this pull request as draft March 17, 2026 14:54
@samwillis samwillis changed the title feat(examples): add wa-sqlite OPFS persistence demo feat: add persisted sync metadata support Mar 17, 2026
@kevin-dp kevin-dp changed the title feat: add persisted sync metadata support feat(examples): add wa-sqlite OPFS persistence demo Mar 18, 2026
@kevin-dp kevin-dp force-pushed the examples/offline-transactions-wa-sqlite-demo branch from 143cf97 to 6a9d96d Compare March 18, 2026 10:32
@kevin-dp kevin-dp marked this pull request as ready for review March 18, 2026 10:35
@kevin-dp
Copy link
Contributor Author

@samwillis I addressed your review in 515fc6c. Vite now builds the app. Typescript is emitting some errors though but this predates this PR and is also the case in main. Something to fix in a follow up PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants